Sprite 1984 - 1993/Sprite 1984 - 1993.iso/lib/tex/textyl/textyl.shar9.Z/textyl.shar9

Text File | 1987-08-10 | 64.4 KB | 1,509 lines

#!/bin/sh
# to extract, remove the header and type "sh filename"
if `test ! -s ./README`
then
echo "writing ./README"
cat > ./README << 'E_O_F'


This is TeXtyl, a post-processor for TeX, which
allows you to typeset graphic line-drawings in
a device-independent manner. It makes use of the \special
facility of TeX to insert commands into the original
 .DVI file produced by TeX, and post-processes that
file, producing another .DVI file for spooling to
your favorite printer.

TeXtyl is written in Pascal because of portability
requirements while under development at Ohio State.  For that
reason, the main portion is one monolithic file, with hooks
into Unix (in a manner similar to that of  "dvitype").  The
original TeXtyl has/had the ability to typeset musical beams.
The enclosed version does not have that ability for reasons of
space and utility. If you feel that you really need it, write
to me at the address below.  Positive suggestions and
ideas for improvements are welcomed, as are actual
improvements to the code.

Also included is the TeXtyl manual, describing
how to use TeXtyl. It is a LaTeX document, using
TeXtyl-commands for examples. It is also available
as a technical report from Ohio State University's
Computer & Information Sciences Dept. at
1036 Neil Avenue, Columbus, OH 43210.
TR #OSU-CISRC-4/87-TR9.  The current version has the
added flexiblity of patterned lines, which is not
reflected in the OSU report.

Finally, in a subsequent posting, are the vector fonts
for actually typesetting the graphic figures. Although
given at a 300dpi resolution, the fonts were created
for device-independence. The file "vecbase.mf" is
included, but has not been translated to the newer
version of Metafont. See the TeXtyl manual for
implementation details of the vector fonts.

This posting comes in several pieces. The directory
stucture currently looks like:
./TeXtyl
README    doc/       src/       vecfonts/

./TeXtyl/doc:
Makefile  TYLMAN.02 TYLMAN.05 TYLMAN.08 TYLMAN.11
TYLMAN.00 TYLMAN.03 TYLMAN.06 TYLMAN.09 TYLMAN.12
TYLMAN.01 TYLMAN.04 TYLMAN.07 TYLMAN.10 TYLMAN.13
textyl.tex

./TeXtyl/src:
h00vars.h textyl.pas.aa textyl.pas.ad textyl.pas.ag
makefile  textyl.pas.ab textyl.pas.ae textyl.pas.ah
texpaths.h textyl.pas.ac textyl.pas.af tylext.c tylext.h

./TeXtyl/vecfonts:
vecfonts.shar.aa  vecfonts.shar.ab
vecfonts.shar.ac  vecfonts.shar.ad


NOTICES:
TeXtyl was written by John Renner between 1984-1987
while at the Ohio State University, and elsewhere/when.
These files and the TeXtyl system are Copyright (c) 1987 by
John S. Renner, All rights reserved. You may
freely use this program, as long as you do no
sell it (nor any derivatives of it),
and as long as I receive a copy of all modifications.
This copyright notice must stay intact and accompany
the TeXtyl sources and manual.

The program, TeXtyl, and the vector fonts were
derived either independently or from sources noted
in the TeXtyl manual. There is absolutely NO relationship
between this work and the work done by Adobe Systems, Inc.,
as TeXtyl was written entirely and independently by
John Renner prior to association with that company.

Current Address: John Renner
        100 N Whisman #211
        Mountain View, CA 94043

  adobe![e-mail]

E_O_F
else
  echo "will not over write ./README"
fi
chmod 644 ./README
if [ `wc -c ./README | awk '{printf $1}'` -ne 3111 ]
then
echo `wc -c ./README | awk '{print "Got " $1 ", Expected " 3111}'`
fi
if `test ! -s ./SUPPLEMENT`
then
echo "writing ./SUPPLEMENT"
cat > ./SUPPLEMENT << 'E_O_F'
Archiver's note

This program is known to work on BSD type systems. Ports to WEB, C and
other OSes are encouraged. Remember to send changes to the author
first.

I have taken the liberty of making some changes. In three places (twice
in the docs, once in the program) I have changed the fonts from am to
cm. I have edited texpaths.h to be more typical. Installers should use
the same texpaths.h as TeX uses. The fonts are in pk format (more
compact).

    Ken
    June 1987
    [e-mail]
E_O_F
else
  echo "will not over write ./SUPPLEMENT"
fi
chmod 644 ./SUPPLEMENT
if [ `wc -c ./SUPPLEMENT | awk '{printf $1}'` -ne 498 ]
then
echo `wc -c ./SUPPLEMENT | awk '{print "Got " $1 ", Expected " 498}'`
fi
if `test ! -d ./doc`
then
  mkdir ./doc
  echo "mkdir ./doc"
fi
if `test ! -s ./doc/Makefile`
then
echo "writing ./doc/Makefile"
cat > ./doc/Makefile << 'E_O_F'
#    Makefile for TeXtyl Manual
LATEX = latex
INCLUDES = TYLMAN.00 \
    TYLMAN.01 \
    TYLMAN.02 \
    TYLMAN.03 \
    TYLMAN.04 \
    TYLMAN.05 \
    TYLMAN.06 \
    TYLMAN.07 \
    TYLMAN.08 \
    TYLMAN.09 \
    TYLMAN.10 \
    TYLMAN.11 \
    TYLMAN.12 \
    TYLMAN.13


tylman:    ${INCLUDES} textyl.tex
    cat ${INCLUDES} > tylman.tex
    $(LATEX) tylman.tex
    /bin/rm tylman.tex
E_O_F
else
  echo "will not over write ./doc/Makefile"
fi
chmod 644 ./doc/Makefile
if [ `wc -c ./doc/Makefile | awk '{printf $1}'` -ne 338 ]
then
echo `wc -c ./doc/Makefile | awk '{print "Got " $1 ", Expected " 338}'`
fi
if `test ! -s ./doc/TYLMAN.00`
then
echo "writing ./doc/TYLMAN.00"
cat > ./doc/TYLMAN.00 << 'E_O_F'
%
%    LaTeX file for  the TeXtyl Manual
%    Copyright (c) 1986, 1987  John S. Renner
%

\documentstyle[twoside,12pt]{report}
\makeindex
\pagestyle{plain}
\pagenumbering{roman}
\begin{document}
\bibliographystyle{plain}
\hfuzz 5pt
\vfuzz 3pt
\hoffset 1in
\voffset 1in
\hyphenchar\tentt=-1
% big tt font
\font\btt=cmtt10 scaled \magstep2
\hyphenchar\btt=-1
% font for small caps
\font\smallrm=cmr10

% special comma
\def\Coma{$\raise 2.5pt\hbox{\btt ,}$}
% macro for specifying a parameter
\def\Prm#1{\leavevmode \hbox{$\>\langle${\it #1\/}$\rangle\,$}}
% macro for specifying an optional parameter
\def\Opt#1{\leavevmode \hbox{$\>\lbrack\langle${\it #1\/}$\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack\,$}}
% optional parameter without large comma
\def\sOpt#1{\leavevmode \hbox{$\>\lbrack\langle${\it #1\/}$\rangle\,
\rbrack\,$}}
% used for simple verbatim environment using | | delimiters
%  taken from TeXbook
\chardef\other=12
\def\ttverbatim{\begingroup \catcode`\\=\other \catcode`\{=\other
        \catcode`\}=\other \catcode`\$=\other \catcode`\&=\other
    \catcode`\~=\other \catcode`\%=\other \catcode`\#=\other
    \obeyspaces \obeylines \tt}
{\obeyspaces\gdef {\ }}
\outer\def\begintt{$$\let\par=\endgraf \ttverbatim \parskip=0pt
   catcode`\|=0 \rightskip=-5pc \ttfinish}
{\catcode`\|=0 |catcode`|\=\other
  |obeylines
  |gdef|ttfinish#1^^M#2\endtt{#1|vbox{#2}|endgroup$$}}
\catcode`\|=\active
{\obeylines\gdef|{\ttverbatim\spaceskip=.5em plus .25em minus .15em\let^^M=\  \let|=\endgroup}}
%
% macro for figures for Tyling
\input{textyl}

\newcommand{\TT}{{\it\TeX tyl\/} }
\newcommand{\TTN}{{\it\TeX tyl}}
\newcommand{\DVI}{{\smallrm DVI}}
\newcommand{\Makeodd}{{\ifodd\count0{\newpage\mbox{\  }\newpage}\fi}}

\title{\TeX tyl: a line-drawing interface for \TeX}
\author{John S. Renner}
\date{14 March 1987
\thanks{Copyright \copyright 1987~John~S.~Renner All rights reserved.}}
\maketitle
\clearpage %end page 0
\begin{verse}
\it Geometry can produce legible letters,\\
 but art alone makes them beautiful.\\
\end{verse}\par
\noindent\begintyl{260 pt}[1in]
\special{tyl beginfigure "zapf"}
\special{tyl line m 2 1,92; 45,92}
\special{tyl line m 2 1,92; 1,48}
\special{tyl line m 2 1,48; 111,48}
\special{tyl line m 2 45,92; 45,4}
\special{tyl line m 2 12,48; 12,92}
\special{tyl line m 2 23,48; 23,92}
\special{tyl line m 2 34,48;34,92}
\special{tyl line m 2 1,70;45,70}
\special{tyl line m 2 1,92; 23,48}
\special{tyl line m 2 1,92; 89,4}
\special{tyl line m 2 23,92;1,70}
\special{tyl line m 2 23,92;1,48}
\special{tyl line m 2 23,92; 45,48}
\special{tyl line m 2 45,92;1,48}
\special{tyl line m 2 45,92; 23,48}
\special{tyl line m 2 1,70,23,48}
\special{tyl arc m 2 11 @ 12,81 270,90}
\special{tyl arc m 2 11 @ 34,81 10 10}
\special{tyl arc m 2 11 @ 34,59 10 10}
\special{tyl arc m 2 11 @ 12,59 270 90}
\special{tyl arc m 2 22 @ 23,70 10 10}

\special{tyl line m 2 45,92; 111,26}
\special{tyl line m 2 1,48; 45,4}
\special{tyl line m 2 45,4;100,60}
\special{tyl arc m 2 32 @ 45,48 10 10}
\special{tyl line m 2 45,4; 89,4}
\special{tyl line m 2 89,4; 89,60}
\special{tyl line m 2 89,4 111 26}
\special{tyl arc m 2 22  @ 67,26 10 10}
\special{tyl line m 2 67 26; 111 26}
\special{tyl arc m 2 16 @ 89,26 10 10}
\special{tyl line m 2 89,26; 111,48}
\special{tyl arc m 2 11 @ 100,37 10 10}
\special{tyl line m 2 100,37;100,60}
\special{tyl line m 2 111,26;111,48}
\special{tyl line m 2 111,48; 100,60}
\special{tyl arc m 2 8 @ 100 48 10 10}
\special{tyl arc m 2 6 @ 94 54 10 10}
\special{tyl line m 2 89,60; 100 48}
\special{tyl line m 2 95,54; 83 54}
\special{tyl arc m 2 4 @ 89 54 10 10}
\special{tyl line m 2 89 54; 100 54}
\special{tyl line m 2 89,60;83,54}
\special{tyl line m 2 89, 60; 100 60}
\special{tyl line m 2 83,54; 83,48}
\special{tyl line m 2 84,48; 89,54}
\special{tyl arc m 2 3 @ 86 51 10 10}
\special{tyl endfigure "zapf"}
\endtyl
\par
\nobreak
\begin{verse}
\it Art begins where geometry ends,\\*
and imparts to letters a character\\*
transcending mere measurement.\\*
\hskip 2in\hbox{\smallrm Paul Standard}
\end{verse}\index{Zapf{,} Hermann}\index{Standard{,} Paul}
\newpage %end page 1
\mbox{   }
\newpage %clear page 2
\tableofcontents

\Makeodd
E_O_F
else
  echo "will not over write ./doc/TYLMAN.00"
fi
chmod 644 ./doc/TYLMAN.00
if [ `wc -c ./doc/TYLMAN.00 | awk '{printf $1}'` -ne 4174 ]
then
echo `wc -c ./doc/TYLMAN.00 | awk '{print "Got " $1 ", Expected " 4174}'`
fi
if `test ! -s ./doc/TYLMAN.01`
then
echo "writing ./doc/TYLMAN.01"
cat > ./doc/TYLMAN.01 << 'E_O_F'
\chapter*{ Introduction}
\label{introduction}
\TT\index{{\TT}} is a prototype post-processing system to be used in
conjuction with {\TeX}\index{{\TeX}}\cite{knuth-tex82}, the typesetting program by Donald
Knuth.  The purpose of \TT is to ``draw'' lines and curves in a
device-independent manner. \TT is a post-processor that
interprets certain commands in a {\DVI}\index{DVI}
({\underline d}e{\underline v}ice-{\underline i}ndependent)
file that is the
output of {\TeX} and contains the actual typesetting commands.
\TT will produce as its output another
{\DVI} file that contains the commands to typeset the lines and
curves on a printer or output device.\par

In the current version of \TT (version 1.2 of March 1987), the simple line drawing
capabilities\index{capabilities} include several general types of straight lines, arcs, and
spline curves. Advanced features of \TT are for {\it MusiCopy}\index{MusiCopy}, the
music-typesetting\index{music} project  at the Ohio State
University\cite{gourlay}, namely typesetting ties, slurs, and beams.\par

The name\index{{\TT}, name} for \TT comes from three ideas: (1) a proper computer graphics
term for rendering images is called ``tiling,'' (2) the
mis-pro\-noun\-ci\-ation of the name sounds like ``textile,'' which evokes an image
of lines and bargello effects from weaving, and (3) this process of ``tyl''-ing\index{tyling} comes after {\TeX}.\par

The main design goals\index{design goals} of \TT were (1) the minimization of data required
to typeset graphics on printers capable of setting only characters at
arbitrary positions on a page,
(2) the adherence to the  {\DVI} format of {\TeX} output for specifying the
way to typeset a document in a device-independent manner,  (3)
 a simple, portable interface that would not require a change to the
functionality or design of {\TeX}, and (4) a user interface that is easy to
use by people and programs alike.\par

\TT was not intended to mimic nor replace sexy programs like
{\it Ideal\/}\index{Ideal}\cite{vanwyk}, which know about constraints
and alignment niceties.
Rather, \TT is designed to
take care of medium-level details for {\TeX} for use on printing devices not
capable of directly accessing and
loading full bitmaps\index{bitmaps} produced by such systems as {\it
PostScript\/}\index{PostScript}\cite{adobe}. It is clear that {\DVI}-format is a subset of {\it
PostScript}, but a large community of users are not able to make use of such
a super-set, and \TT is intended to provide line-drawing
capabilities\index{capabilities} for them.\par

Probably the best way to read this manual\index{{\TT}, how to read manual}
 is to read the first four (4)
chapters, and skip right to the chapter entitled {\it Future Extensions},
for a good introduction to \TTN. The other chapters deal with details of
the innards of \TTN, and describe the design in successively finer
detail.\par

I would like to thank John Gourlay, and Clayton Elwell for their support,
comments, reminders, and good ideas during this three-year labor, and the
{\smallrm CGRG} for not hassling me about this.\par

\Makeodd
E_O_F
else
  echo "will not over write ./doc/TYLMAN.01"
fi
chmod 644 ./doc/TYLMAN.01
if [ `wc -c ./doc/TYLMAN.01 | awk '{printf $1}'` -ne 3110 ]
then
echo `wc -c ./doc/TYLMAN.01 | awk '{print "Got " $1 ", Expected " 3110}'`
fi
if `test ! -s ./doc/TYLMAN.02`
then
echo "writing ./doc/TYLMAN.02"
cat > ./doc/TYLMAN.02 << 'E_O_F'
\chapter{The Basics}
\pagenumbering{arabic}
\label{getting-started}So, let's draw.
I will assume that the reader  has a reasonably good working knowledge of how to
use {\TeX}\index{{\TeX}} and/or {\LaTeX}\index{{\LaTeX}}, and sort of understands
 Knuth's\index{Knuth{,} Donald} concept of ``boxes,''\index{boxes} and their
attributes of height, width, and current position\index{current position}. We need these concepts
because our direct interface is with {\TeX}, in the form of a {\tt .tex}
text-file\index{{\tt .tex} text file}. To typeset the line-drawings, we ask {\TeX} to place our drawing
at the current position on the page. Throughout this manual, I will provide
some examples of drawings to illustrate ideas. These figures are thumb-nail
size, but should be sufficient to get the idea across without using up lots
of space on a page.
 Let's look at a simple example: After typing |\input{textyl}| \index{{\tt
textyl.tex} file}\index{{\tt input}}
near the
beginning of your file, but after any required preamble\index{preamble}, we
can obtain a trivial drawing like:
\index{line example}\par
\noindent\hskip 2in\begintyl{2truecm}[1in]
\special{tyl line  4 20, 0; 80,30}
\endtyl\par
\noindent Simple, but we achieved this
 line by typing
\begin{verbatim}
...a trivial drawing like:\par
\noindent\hskip 2in\begintyl{2cm}[1in]
\special{tyl line  4 20, 0; 80,30}
\endtyl\par
\end{verbatim}

The |\begintyl{2cm}[2in]| and |\endtyl| commands\index{macros}\index{space macros} were
\index{{\tt begintyl}}\index{{\tt endtyl}}\index{macros, {\it see} {\tt begintyl}}to give us some
space\index{space} to ``paste'' the picture in
(about 2 centimeters of vertical space, 1 inch of horizontal space,
and offset from the left-most margin by 2 inches),\footnote{See also Appendix~\ref{secapp}}
 and the |\special...|\index{{\tt special}} is our way of asking for the above drawn line.
 Here, we must use a ``|\special|'' to talk to {\TeX}
at this level. Later, \TT will actually do the work involved in
typesetting that line that {\TeX} recorded as being at this place on the
page. The |\special|\index{specials} is a way to make a kind of note or memo that {\TeX}
will write into the {\DVI} file for some other program like
\TT to work with, or choose to ignore, like most {\DVI}
filters do. \par

Let's look at what |\special{tyl line 4 20, 0; 80,30}| is all about. First,
|tyl| is a name-string\index{{\tt tyl} name-string} asserting that this command
 should make sense to \TTN.
Next, |line| is the name of the graphic
primitive\index{primitive}
 to typeset: a
line segment (we will get to the other primitives later). The rest of the ``special''
notes that the thickness\index{line thickness} of the line is $4$, and to draw the line from a
mark 20 printer's-points\index{printer's points, measurement} to the
 right of the current position to a mark 80
points over and 30 points higher from that current position. Mathematically,
we are using a {\bf first-quadrant} cartesian
 coordinate-space\index{cartesian-space}\index{coordinates}
 whose origin\index{origin}\index{coordinates, origin} is at the
current position\index{current position} on the page, and we are drawing a line from $(20,0)$ to
$(80,30)$ in integer units\index{measurement, units} of printer's-points in that space. It looks like this (magnified):\par
\noindent\hskip 1in\begintyl{130 pt}
\special{tyl beginfigure}
\special{tyl line m 2 0,0 0,40}
\special{tyl label m 1  0 43 "+Y"}
\special{tyl line m 2 0 0 90 0}
\special{tyl label m 1 93 0 "+X"}
\special{tyl arc m 1 2 10 10}
\special{tyl line m 8 20,0;80,30}
\special{tyl line m 1 0 10, -2,10}
\special{tyl line m 1 0 20, -2 20}
\special{tyl line m 1 0 30 -2 30}
\special{tyl line m 1 0 40 -2,38}
\special{tyl line m 1 0 40 2 38}

\special{tyl line m 1 10 0 10 -2}
\special{tyl line m 1 20 0 20 -2}
\special{tyl line m 1 30 0 30 -2}
\special{tyl line m 1 40 0 40 -2}
\special{tyl line m 1 50 0 50 -2}
\special{tyl line m 1 60 0 60 -2}
\special{tyl line m 1 70 0 70 -2}
\special{tyl line m 1 80 0 80 -2}
\special{tyl line m 1 90 0 88 2}
\special{tyl line m 1 90 0 88 -2}
\special{tyl endfigure}
\endtyl
\par
\vskip 10pt
\noindent where we have emphasized the origin of the quadrant, and used
tick-marks for every ten printer's-points. In reality, someone preparing a
figure would sketch\index{figures, preparation}
\index{preparing a figure} something out on grid paper, and then use those
coordinates for use in the |\special|. If he were really in luck, he
could use a graphic editor that would take care of such numeric details, and
maybe even output the  |\special| strings for direct insertion into the
{\tt .tex} file. Maybe. For now, we will have to stick to the grid-paper
method. The only things that we have to remember are that the origin\index{grid-origin} of our
quadrant is placed at the position\index{current position} on the page where we invoke the
|\special| of {\TeX}, and that we may want to leave white space\index{space}\index{leaving white space} for our
graphic to be drawn in. This last constraint is because {\TeX} does not
really know about the size of our drawing, it thinks that the |\special| is
a ``box''\index{boxes} with zero height and width placed at the current position on the
page. It is up to us to decide how much {\it real\/} space to tell {\TeX} to
leave for our drawing to be put into later by \TTN.\par
In the example above,
and the following examples, we will put our |\special| strings within an
environment that makes it easy to specify where the origin of our quadrant
should be placed. For example, |\begintyl{4cm}[1in]| \index{{\tt begintyl}}
 tells {\TeX} to place
our origin 4 centimeters down from where it was just sitting.
A horizontal width is an optional second parameter to |\begintyl|,
and is enclosed in square braces immediately following the vertical
displacement parameter (with no spaces in-between). So |\begintyl{5cm}|
would place our origin 5 centimeters below the current position, with no
relative horizontal width. Other spacing requirements have to be done by
hand (e.g., like typing |\hskip 1in| before the |\begintyl|), or by putting the whole
|\begintyl| \ldots |\endtyl| group within a containing environment (e.g.,
\LaTeX's |figure| environment).
 We could, if
we wanted,
leave no extra white-space\index{leaving no space} and have the drawing extend  into
 and over any text that {\TeX} may typeset
before {\it or\/} after we invoke a |\special{tyl ...}| command. We would,
of course, start that  tyling-environment with a
 |\begintyl{0pt}| command, and finish with the |\endtyl| command, and it
might do something
 like \begintyl{0pt}\special{tyl arc m 3 5 @4 0;5 5}\endtyl this.
\par

\goodbreak Once we are satisfied with our {\tt .tex}\index{{\tt .tex} text file}
 file containing |\special| strings
requesting line-drawings, we run the {\tt .tex} file through
 {\TeX}\index{{\TeX}} or {\LaTeX}\index{{\LaTeX}}, and
(barring any fatal errors) end up with a {\tt .dvi} file\index{{\tt .dvi} file}.
We now run\index{running {\TT}}
 this {\tt .dvi} file through \TT which goes through the file and converts our
|\special| strings left-over from {\TeX} into commands to actually typeset
the line-drawing. The whole process might look something like this:\par

\bgroup\small
{\it prompt:}\underbar{\tt tex}\par
{\tt This is TeX, Version mumble...}\par
{\tt **}\underbar{\tt myfile.tex}\par
\hspace*{6em}$\ldots$ {\it output from \TeX}\par
{\tt Output written on myfile.dvi ( n pages , m bytes).}\par
{\it prompt:}\underbar{\tt textyl}\par
{\tt This is TeXtyl, Version blah...}\par
{\tt DVI-input File Name:}\underbar{\tt myfile.dvi}\par
{\tt DVI-output File Name}\par
{\tt (different than input name)[default of myfile.tyl]:}
\underbar{\tt myfile2.dvi}\par
\hspace*{6em}$\ldots$ {\it output  from \TT}\par
{\tt Output written on myfile2.dvi}\par
{\tt Log written on myfile2.tlog}\par

\egroup
\noindent So there you have it. All we have to do is give this
new {\tt .dvi} (or {\tt .tyl}) file to
a favorite {\DVI} filter\index{DVI-filters}, and look at the document with the
line-drawing results on that particular filter's output device\index{output
device}
(usually paper or a bitmapped screen). You should
contact your local maintainer\index{local maintainer} if \TT or the filter
 cannot find the right fonts, and try again.\par
By the way, the {\tt .tlog} file is useful for finding out about the
``tyling'' of the {\tt .dvi} file. Besides noting any errors, the log file
contains the approximate height and depth of each non-trivial figure. A
portion of the {\tt .tlog}\index{{\tt .tlog} file} file for this document
might look like:
\vspace*{-20pt}

{\footnotesize\begin{verbatim}
17] [
Figure #1 on page 18 is approx. 33 pts high and 47 pts wide

Figure #2 on page 18 is approx. 32 pts high and 51 pts wide

Figure #3 on page 18 is approx. 27 pts high and 45 pts wide

Figure #4 on page 18 is approx. 31 pts high and 82 pts wide
18] [19] [20] [
\end{verbatim}

}
This information allows you to re-edit the parameters to |\begintyl| so that
\index{{\tt begintyl}} they can better approximate the actual sizes of the figures.\par
\medskip\filbreak
Let's try a slightly more complicated example: drawing a spline.\index{spline, example}
\TT understands drawing smooth spline curves\index{spline curves}\index{curves} through
in\-teger co\-ordinate points (both positive and negative)\index{spline, coordinates}
 on our grid. For example:
\vspace*{-10pt}
\begin{verbatim}
\begintyl{3cm}[1in]
\special{tyl spline m 4 K 7 5,10; 9,14; 15,7;22,13;
                               17,14;12,5;7,0;}
\endtyl\par
\end{verbatim}
yields\par
\noindent\hskip 1in\begintyl{2cm}[1in]
\special{tyl spline m 4 K 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0; }
\endtyl
\par\filbreak
\noindent Here, we are using units of millimeters for measurement (denoted
by an |m| or |M|,\index{{\tt M}-marker}\index{millimeters, measurement} a line thickness of $4$, and we
 want to use a Catmull-Rom type spline\index{spline,
Catmull-Rom}\index{Catmull-Rom splines}
(denoted by |k| or |K|\index{{\tt K}-marker}---also the default type\index{spline,
default}
 if none is specified). We
 specify that there are $7$ control points\index{spline, control-points}
to interpolate through, and then
list those $x, y$ pairs.  Some things are optional
\index{defaulting values}\index{optional values}
 for you (like the spline type, or the units of measure), but
some are {\it not\/} (notably the line-thickness and the number of control points).
As we go through these examples, I will point out the minimum that we
need to specify a graphic primitive, and note other options or features that
we might want to use. For a detailed look at the specifications of the
primitives, please refer to the \underbar{\it User-Level
Details} in chapter~\ref{user-level}.\par\filbreak

Let's try one more type of spline-primitive: the thick-n-thin
spline\index{ttspline}\index{Thick-n-thin spline}\index{spline, ttspline}. This
is a primitive that lets us specify a spline of varying line thickness along
the spline. An example\index{ttspline, example} invocation might be:
\begin{verbatim}
\special{TYL ttspline m 5 4,6; 14,25; 18,19; 21,15; 24,8;
                           10;    2;    6;     3;     8}
\end{verbatim}\par
\noindent\hskip 1in
\begintyl{4cm}[2in]
\special{tyl ttspline m 5 4,6; 14,25; 18,19; 21,15; 24,8;
              10;    2;    6;    3;    8}
\endtyl\par
\noindent It looks similar to the |spline| primitive, but here we did not
specify a single line thickness right after the |m|\index{{\tt M}-marker}
 measure-marker. The |5|
refers to the number of control-points as before, then is followed by the
$(x,y)$ coordinate pairs, and then  the line-thicknesses\index{ttspline, thicknesses}. The first
number (here, |10|) refers to the line thickness at the first control-point
(here, $(4,6)$ ); the next for the second control-point, etc. We did not
need to align the thicknesses under the control-points, but  it
makes the correspondence more apparent.  We did not
specify the type of spline to use, so the Catmull-Rom interpolating spline
was used by default\index{ttspline, defaults}. We could have inserted a
 |b| marker\index{{\tt B}-marker}
 directly before the number of control-points,\label{thebases}
and gotten a spline using the B-spline basis\index{B-spline
basis}.\index{spline, B-spline}
 Using
a |d| marker\index{{\tt D}-marker} yields a spline with the Cardinal
basis\index{Cardinal basis},\index{spline, Cardinal} and
an |i|\index{{\tt I}-marker} would indicate an
Interpolating B-spline\index{B-splines, interpolating-type}\index{spline,
Interpolating B-spline}
 (which is a little different)\index{interpolating B-spline}. We will
look closer at these spline-types on page~\pageref{diffsplines}.
\par\filbreak

If you've been very observant, you may have noticed that the way we type in
the |\special| strings\index{typing in special
strings}\index{specials, typing in}
 (the letters and numbers within the |{| -- |}| pair)
has been rather indiscriminant about upper vs. lower-case\index{specials, case insensitivity}.
 That's okay. \TT
 has only a few things to worry about, and so it will try to
figure things out for you. It is pretty lenient about how you
punctuate\index{specials, punctuation}
 and
separate (``delimit'')\index{delimiters} keywords\index{keywords}
 and markers\index{markers}.\goodbreak\filbreak  We only have to remember
\begin{enumerate}
\item the relative ordering of the keywords and integers,
\item being careful to avoid
mis-using the word markers\footnote{See the index for a list of markers} in
the wrong places, and
\item supplying enough parameters that are expected.
\end{enumerate}
Other than its own macro-expansions, {\TeX} really
 doesn't care about the ``meaning'' of the final strings that
 goes inside the curly braces of the
|\special{...}| command-strings, only \TT does.\par

We'll briefly look at an example of one more graphic primitive, and then get
on to more advanced topics. \TT has the ability to draw arcs and
circles like\index{arcs}\index{circles}:\par
\noindent\hskip 2in\begintyl{7truecm}[2in]
% 15-Mar-87 15:51:23
% TeXtyl figure written with width= 198 mm and height= 206 mm
%   you may have to scale it with Transform or Fit operators in beginfigure
\special{tyl beginfigure m W 198 206 F 50 50}
\special{tyl arc m 3 c 64 @(134 114) 357 54}
\special{tyl arc m (T 120 80 0 0 0) 3 c 31 @(36 31) 10 10}
\special{tyl arc m 3 c 53 @(129 77) 94 58}
\special{tyl arc m 3 c 66 @(85 140) 27 323}
\special{tyl arc m 1 c 57 @(57 100) 10 10}
\special{tyl endfigure}
\endtyl\par\filbreak
\noindent Arcs are drawn from an initial angle (measured
from the horizontal (positive x-axis) in integer degrees) counter-clockwise
to a final angle with
the arc centered about the origin.\index{arcs, angles}\index{arcs, center}
 If the
initial angle is the same as the final angle, we get a full circle\index{circles}\index{arcs, circles}.
A simple arc invocation might look like\index{arcs, example}:\par
|\special{tyl arc m 2 3, 48, 280}|\par
\noindent which would draw an arc of line thickness $2$, a radius\index{arcs, radius} of $3$
millimeters, from an initial angle of 48 degrees until the final angle of 280
degrees centered about the origin. We could specify that the arc is to be
centered\index{arcs, centering}
elsewhere by using a special |@|\index{{\tt @}-marker} marker. So,\par
|\special{tyl arc m 2 3, @ 7,7; 10 10  }|\par
\noindent would draw an arc of line-thickness $2$, radius of $3$ mm as before,
but centered at $(7,\, 7)$ from the origin. Also, since the initial and final
angles are the same in this example (|10|), we would get a full circle.
\par\vfill\pagebreak[4]
%\Makeodd
E_O_F
else
  echo "will not over write ./doc/TYLMAN.02"
fi
chmod 644 ./doc/TYLMAN.02
if [ `wc -c ./doc/TYLMAN.02 | awk '{printf $1}'` -ne 15730 ]
then
echo `wc -c ./doc/TYLMAN.02 | awk '{print "Got " $1 ", Expected " 15730}'`
fi
if `test ! -s ./doc/TYLMAN.03`
then
echo "writing ./doc/TYLMAN.03"
cat > ./doc/TYLMAN.03 << 'E_O_F'
\chapter{Advanced Features}
\label{advanced-features}In the previous chapter, we saw basic examples of most of the graphic
primitives available in \TTN, how to invoke them\index{primitives, invoking}, and some of
the parameters\index{primitives, parameters} to the primitives. We also saw examples of how we interface
with {\TeX} using the |\special| command strings, and how the origin of our
drawing quadrant is placed at the reference point  of the ``box'' containing
the |\special| (usually the lower-left corner of the box created with the
|\begintyl| and |\endtyl| macros.\index{macros}\index{boxes}
 (see the {\TeX book}\cite{knuth-tex82}\index{\TeX book} for a better explaination of
``specials''). The rest of this chapter will look more at
the parameters available for the primitives, and how we can
combine\index{primitives, combining}\index{combining primitives}
primitives and manipulate them.\par

\section{Transforms}
\label{transforms}\index{transforms}
The most interesting additional parameter for the primitives is a transform
operation. It allows us to modify an already-exisiting definition of a
primitive without our having to totally re-edit the |\special|
string, nor having
to explicitly re-compute the  coordinates of the line/spline points.
Thus we can take a simple definition similar as before, like:\par
|\special{tyl line m 4 0,8; 39,44}|\par
\noindent and change its size, or rotate it, or translate (shift)
its position\index{scaling}\index{rotation}%
\index{translating}\index{primitives, scaling; rot\-ating; trans\-lating}
without completely changing the actual text of the
 specification of the control points (this is really useful
when dealing with splines having many control points).
\index{transforms, scaling}\index{transforms, rotating}
\index{transforms, translation}
\filbreak
 Let's look at an
example, and then go into more detail about the transform. For example, to
rotate the above definition about its center by 60 degrees
counter-clockwise, all we have to specify is
|\special{tyl line m T (100, 100, 0, 0, 60) 4 0,8; 39, 44}|
 which yields\index{transforms, example}\par
\noindent\hskip 1in\begintyl{1in}[2in]
% 15-Mar-87 15:47:50
% TeXtyl figure written with width= 196 mm and height= 71 mm
%   you may have to scale it with Transform or Fit operators in beginfigure
\special{tyl beginfigure m W 196 71 F 51 51}
\special{tyl line m 4 c 170 0 154 71}
\special{tyl line m 4 c 54 61 0 11}
\special{tyl line m 1 c 109 28 114 37}
\special{tyl line m 1 c 107 45 114 37}
\special{tyl line m 1 c 110 34 87 34}
\special{tyl line m 1 c 111 37 89 37}
\special{tyl line m 1 c 110 39 87 39}
\special{tyl endfigure}
\endtyl\par
\noindent as expected. We use the |T|\index{{\tt T}-marker} marker to note the need for a
transformation, and follow it by five numbers\index{transforms, parameters}.
 The first two are for
scaling, the next two for translation, and the last (here, |60|) is for our
rotation.  In general, the
format for specifying some transformation on the currently-specified points
is:\par
\qquad{\btt T}\ \Prm{Sx}\Coma\Prm{Sy}\Coma\Prm{Tx}\Coma\Prm{Ty}\Coma\Prm{Rot}\Coma\par
\noindent where \Prm{Tx} and \Prm{Ty} are translations of the object in
 the $X$ or $Y$ direction, respectively, by some signed distance according to the
current units of \Prm{measure} (|m|\index{{\tt M}-marker} still means millimeters in the above example).
 \Prm{Rot} is a signed integer angle (in degrees) \index{rotation}
by which\index{rotation, using degrees measurement}
to rotate the primitive counter-clockwise about its center.
  \Prm{Sx} and \Prm{Sy} are\index{transforms, parameters}
integer scale parameters representing the real values of the
transform multiplied by 100. For example, if you wanted to scale the drawing
in the $X$ direction (relative to the drawing's center)
 by an additional 50\% (i.e., scale by 1.5),
\Prm{Sx} would be 150. Negative values are usuable, too, so
mirroring\index{transforms, mirroring} about the $Y$ axis is achievable by
scaling in the negative $X$ direction, like $\Prm{Sx} = -100$.
To obtain any transform, {\it all\/} the transform parameters must be
specified. A no-op transform\index{transforms, no-op} would look kind of like
{\tt T~(100,~100,~\kern-1pt0,~\kern-1pt0,~\kern-1pt0)} in the middle of
the |\special|. \par

\section{Figures}
\label{figures}
The last major \TT concept is the idea of combining
several primitives\index{primitives, combining} into what we call a
``figure.''\index{figures}\index{combining primitives}
This figure can be manipulated either as a single entity  or in parts
by
using the \Prm{transform} operations\index{figures, transforms} described
in the previous section.
These optional figure-level transformations
will transform all the figure's primitives (which may have local
transformations of their own). The result is a nested symbol definition
\index{nested symbols}\index{figures, nested symbols}
that has concatenatable transformations\index{transforms, concatenation}.
This is useful for defining some
 symbol, created from various primitives, and dealing with it
as a unit. For example,  a basic logotype can be defined, and then moved
about, scaled, or rotated as desired {\it without\/} having to change the
original definition of the logotype or its parts from scratch.
These  commands are:\par
\medskip
{\btt\char'134 special\char'173 tyl beginfigure}
{\leavevmode \hbox{$\>\lbrack\langle${\it transform\/}$\rangle\,
\rbrack\,$}}{\btt\char'175}\par
\noindent which opens a level of definition\index{{\bf beginfigure}}\index{figures, defining},
and\par
\medskip
{\btt\char'134 special\char'173 tyl endfigure}{\btt\char'175}\par
\noindent which closes that level of definition\index{{\bf endfigure}}.
 Any calls to a
|\special{tyl ...| primitive within a |beginfigure| -- |endfigure| pair
become part of that figure's definition\index{figures, sub-figures}.
Note the definition of |beginfigure| allows the ability to apply a
transformation at the outer level. A simple example might be:\index{figures,
examples}\vspace*{-10pt}
\begin{verbatim}
\begintyl{2in}
\special{tyl beginfigure}
    \special{tyl line m 2 5,10; 15,15 }
    \special{tyl line m 4 10,20; 16,1 }
    \special{tyl line m 8 15,10; 25,10 }
\special{tyl endfigure}
\endtyl
\end{verbatim}
giving a figure of three lines:\par
\noindent\hskip 2in\begintyl{1truein}[2in]
\special{tyl beginfigure "oflines"}
\special{tyl line m 2 5,10; 15,15 }
\special{tyl line m 4 10,20; 16,1 }
\special{tyl line m 8 15,10; 25,10 }
\special{tyl endfigure "oflines" }
\endtyl\par
\noindent We can also define sub-figures\index{sub-figures} within figures
and apply\label{sub-figures}
transformations\index{transforms, sub-figures} to those, too. The idea looks like:\par
|\begintyl{down-distance}[optional-width]|\par
|\special{tyl beginfigure}|\par
\qquad    $\ldots$\par
\qquad|\special{tyl beginfigure}|  {\it \% Some sub-figure }\par
\qquad    $\ldots$\hbox{\hskip 2in}   {\it \% of other primitives}\par
\qquad|\special{tyl endfigure}|\par
\qquad   $\ldots$\par
|\special{tyl endfigure}|\par
|\endtyl|\par
\noindent Where ``$\ldots$'' means possible other invocations of
primitives with |\special{tyl...}| strings.  We are
able to use spacing and tabbing to nicely indent our |\special| strings,
since {\TeX} considers all that white space to be non-existent within the
|\begintyl| -- |\endtyl| environment.\index{{\tt begintyl}}\index{{\tt
endtyl}}
\par\filbreak

We'll look at a basic figure\index{figures, example}, and apply some
transforms to parts of it.
 For the basic figure, we have:\par
\noindent\hskip 2in\begintyl{1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-1"}
     \special{tyl beginfigure "tex-logo"}
    \special{tyl line m 3 2,13; 10,13}
    \special{tyl line m 3 6,13; 6,6}

    \special{tyl line m 3 8,11;8,4}
    \special{tyl line m 3 8,11;12,11}
    \special{tyl line m 3 8,8; 11,8}
    \special{tyl line m 3 8,4;12,4}

    \special{tyl line m 3 13,13;18,6}
    \special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure  "tyl-logo"}
    \special{tyl line m 3 20,10;24,10}
    \special{tyl line m 3 22,12;22,6}

    \special{tyl line m 3 25,10;27,6}
    \special{tyl line m 3 29,10;26,2}

    \special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent Now let's scale a sub-figure by using a |T|\index{{\tt T}-marker}
 transform at the
|beginfigure| level; i.e., something like
\verb+\special{tyl beginfigure T 60 60 0 0 0}+ :\par
\noindent\hskip 2in\begintyl{ 1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-2"}
     \special{tyl beginfigure "tex-logo"}
    \special{tyl line m 3 2,13; 10,13}
    \special{tyl line m 3 6,13; 6,6}

    \special{tyl line m 3 8,11;8,4}
    \special{tyl line m 3 8,11;12,11}
    \special{tyl line m 3 8,8; 11,8}
    \special{tyl line m 3 8,4;12,4}

    \special{tyl line m 3 13,13;18,6}
    \special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 0 0 0  "tyl-logo"}
    \special{tyl line m 3 20,10;24,10}
    \special{tyl line m 3 22,12;22,6}

    \special{tyl line m 3 25,10;27,6}
    \special{tyl line m 3 29,10;26,2}

    \special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent We can rotate, and then also translate that same
sub-figure and achieve the next two examples. First, a rotation about
the sub-figure's center:\par
\noindent\hskip 2in\begintyl{ 1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-3"}
     \special{tyl beginfigure "tex-logo"}
    \special{tyl line m 3 2,13; 10,13}
    \special{tyl line m 3 6,13; 6,6}

    \special{tyl line m 3 8,11;8,4}
    \special{tyl line m 3 8,11;12,11}
    \special{tyl line m 3 8,8; 11,8}
    \special{tyl line m 3 8,4;12,4}

    \special{tyl line m 3 13,13;18,6}
    \special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 0 0 -35 "tyl-logo"}
    \special{tyl line m 3 20,10;24,10}
    \special{tyl line m 3 22,12;22,6}

    \special{tyl line m 3 25,10;27,6}
    \special{tyl line m 3 29,10;26,2}

    \special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent and now also translated {\it after\/} the rotation:\par
\noindent\hskip 2in\begintyl{1in}[2in]
\special{tyl beginfigure "TeXtyl-logo-4"}
     \special{tyl beginfigure "tex-logo"}
    \special{tyl line m 3 2,13; 10,13}
    \special{tyl line m 3 6,13; 6,6}

    \special{tyl line m 3 8,11;8,4}
    \special{tyl line m 3 8,11;12,11}
    \special{tyl line m 3 8,8; 11,8}
    \special{tyl line m 3 8,4;12,4}

    \special{tyl line m 3 13,13;18,6}
    \special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure T 60 60 -8 -8 -35  "tyl-logo"}
    \special{tyl line m 3 20,10;24,10}
    \special{tyl line m 3 22,12;22,6}

    \special{tyl line m 3 25,10;27,6}
    \special{tyl line m 3 29,10;26,2}

    \special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl\par\filbreak
\noindent Finally, we can take the whole figure, and perform a scale and a
then a rotation on it (we evaluate scaling first, then rotations and finally
translations):\par
\noindent\hskip 2in\begintyl{3cm}[2in]
\special{tyl beginfigure T 80 80 0 0 60  "TeXtyl-logo-5"}
     \special{tyl beginfigure "tex-logo"}
    \special{tyl line m 3 2,13; 10,13}
    \special{tyl line m 3 6,13; 6,6}

    \special{tyl line m 3 8,11;8,4}
    \special{tyl line m 3 8,11;12,11}
    \special{tyl line m 3 8,8; 11,8}
    \special{tyl line m 3 8,4;12,4}

    \special{tyl line m 3 13,13;18,6}
    \special{tyl line m 3 13,6;18,13}
    \special{tyl endfigure}
    \special{tyl beginfigure  "tyl-logo"}
    \special{tyl line m 3 20,10;24,10}
    \special{tyl line m 3 22,12;22,6}

    \special{tyl line m 3 25,10;27,6}
    \special{tyl line m 3 29,10;26,2}

    \special{tyl line m 3 31,13;31,6}
    \special{tyl endfigure}
\special{tyl endfigure}\endtyl
\par\filbreak

\section{Others}
We'll finish off this section with a couple more primitives: a simple spline
example, and the primitives for a music-typesetting project underway at Ohio
State University\cite{gourlay}\index{OSU}. The first example is not really that different from our
first spline example, except that in this case, we have a ``closed''
spline:\index{splines, closed}\index{closed splines} one whose
 first control-point will coincide with its last control-point.
We can type something that looks like:
\begin{verbatim}
\special{tyl spline m 3 b O 8 (10,9) (4,16) (8,23)
        (11,21) (13,17) (20,16) (22,13) (19,8)}
\end{verbatim}\par
\noindent  The |O| (letter ``Oh'')\index{{\tt O}-marker}
  marker denotes a closed spline\index{closed splines}. The default
option is an ``open'' spline\index{open spline}\index{splines, open},
 and can be marked with a |U|\index{{\tt U}-marker} instead of the
|O| if you wish to be explicit.
The difference is in the way that \TT
manipulates the control points when doing the interpolation.
 In this example, we used a B-spline, as marked with a
|b|\index{{\tt B}-marker}, and  we listed {\it only\/} the unique
coordinates to get this nice bean-shape:\par
\noindent\begintyl{3cm}[2in]
\special{tyl spline m 3 b O 8 10,9;4,16;8,23;11,21;13,17;20,16;22,13;19,8}
\endtyl\par

\label{diffsplines}\TT provides three types of spline interpolation which I alluded to on
page~\pageref{thebases}.  The Catmull-Rom basis is probably the most
intuitively useful spline for users. It produces a smooth curve that goes
\index{splines, Catmull-Rom, example}
through the control points (which we can mark with dots):\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 2 K X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
The Cardinal basis\index{splines, Cardinal, example} is of the same family
as the Catmull-Rom. It, too, interpolates through the control points, and is
included for convenience and as an alternative to the Catmull-Rom. For
example:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 2 D X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
The B-spline\index{splines, B-spline, example} is a little different in that
the curve {\it approximates\/} the control points. Using the same control points as
the above example, but using the B-spline basis, we see:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 3 B X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par
For the most part, you will probably want to draw curves through the control
points that you specify, and so the Catmull-Rom basis is the
convenient default. The B-spline type is provided for completeness for users
who might have data using that basis.\par

 There {\it are\/} times when the Catmull-Rom or Cardinal bases give flakey
curves and the B-spline basis is not appropriate either. \TT provides a
fourth type of spline for these situations: an interpolating B-spline
curve.\index{splines, Interpolating B-spline, example} It has the advantages
of Catmull-Rom's interpolation, and the special flexibilities of the
B-spline, but is computationally more expensive. See \cite{wu-abel} or \cite{barsky} for a
complete explanation. Here is an example using the same control points as
the above examples, but using the interpolating B-spline:\par
\noindent\hskip 1in\begintyl{1in}[1in]
\special{tyl spline m 3 I X 8 7 5,10; 9,14; 15,7; 22,13;17,14;12,5; 7,0;}
\endtyl\par

For the {\it MusiCopy\/}\index{MusiCopy} project, we have the ability to draw ties and slurs
\index{ties}\index{slurs}---the long arcs connecting groups of notes. For the most part, I assume
that there is a program that is going to take care of the details of knowing where these
graphic elements are to be placed, and will produce the correct |\special|
string for inclusion in the {\tt .tex} file, but I will give an example for
completeness.\filbreak This graceful arc is produced by specifying a minimum and
\index{ties, {\it see also} slurs}\index{slurs, {\it see also} ties}
\index{ties, example} maximum thickness, and the five control points for the shape.\par
\noindent\begintyl{4truecm}[2in]
\special{tyl tieslur m 2 8 5 5,10; 7,13;15,16;24,17; 28,15 }
\endtyl\par\filbreak

\noindent The call looked like\index{tieslur, example}:\par
|\special{tyl tieslur m 2 8 5 (5,10)(7,13);[15,16];(24,17); 28,15 }| \par
\noindent where |2| and |8| are the min and\index{tieslur, thicknesses}
max thicknesses at the endpoints and the middle, respectively. The following
|5| is for the number of control points, and the five pairs of integers
following that are the coordinates of the points. We use a special way of
producing a smooth and gradual thin to thick to thin line-thickness,
but  will discuss it in a later chapter.\index{ties, and ttsplines}\par\filbreak

The last example is the most specialized for the music project: beams\index{beams}. We'll
just look at an example of how they are called and appear, and leave the
details for the next chapter.\par
\noindent\begintyl{3truecm}[2in]
\special{tyl beginfigure "beams" }
    \special{tyl beam m 0 3,20; 15,23 }
    \special{tyl beam m 0 g 3,10;11,7 }
\special{tyl endfigure }\endtyl\par
\noindent The basic order of the parameters looks something like:\par
|\special{tyl beam m 0 g 3,10;11,7 }|\par
\noindent where |0| (zero) is the ``staff-size,''\index{staff-size}
 |g|\index{{\tt G}-marker} indicates a beam size for
``grace'' notes\index{grace-notes} (|r|\index{{\tt R}-marker}
is the default for ``regular'' sized notes), and the
last two pairs are the coordinates of the line-segment that the beam is to be
centered over.\par

\Makeodd
E_O_F
else
  echo "will not over write ./doc/TYLMAN.03"
fi
chmod 644 ./doc/TYLMAN.03
if [ `wc -c ./doc/TYLMAN.03 | awk '{printf $1}'` -ne 17492 ]
then
echo `wc -c ./doc/TYLMAN.03 | awk '{print "Got " $1 ", Expected " 17492}'`
fi
if `test ! -s ./doc/TYLMAN.04`
then
echo "writing ./doc/TYLMAN.04"
cat > ./doc/TYLMAN.04 << 'E_O_F'
\chapter{User-Level Details}
\label{user-level}
From the user's point of view\index{user's view} using {\TeX}\index{{\TeX}},
 commands\index{{\TeX} commands}\index{specials} that \TT
interprets will look like the word ``|tyl|'', followed by
 the name of the graphic to typeset, then a
list of parameters\index{parameters to {\TT}}\index{{\TT}, parameters}
all enclosed within the curly
braces of a \hbox{|\special{...}|} command.
This use of a |\special| could be produced
by some other program (a graphic editor, for example),
\index{graphic editors} and the text strings merely
inserted into the {\tt .tex} text-file. \par

As far as the user is concerned, he is pasting in a picture at the current
position\index{current position} on the page where he invokes the |\special|. The user should
think of this picture as being a box just big enough to contain all the
lines of his graphic image, and whose first-quadrant cartesian
 origin is the reference\index{origin of quadrant}\index{reference point}
point that will be placed at the current position on the page. Thus, he
might want to  make sure that there is enough blank space \index{blank space}around the current
position on the page to contain the
image before he tries to ``paste it in.'' Space can be created by using
\TeX's |\hskip| or |\vskip|, or \LaTeX's |\hspace| and |\vspace| commands,
\index{{\TeX}}\index{{\LaTeX}} or hoping for the best with \LaTeX's
|figure| environment \index{{\LaTeX}, {\tt figure } environment} surrounding
the box created by |\begintyl| and |\endtyl|.
\par

The kinds of graphic primitives\index{primitives}\index{capabilities}
that \TT knows how to typeset are
uniform-thickness line segments, uniform-thickness splines,
uniform-thickness arcs, variable-thickness
splines, music beams, and music ties/slurs.  Line segments are
merely a subset of splines, and so variable-thickness lines are available by
specifying a spline of just two control points with a thickness at one end
point,\index{primitives, built-up}
 and another thickness at the other end point. The feature here is to have
several primitives available, and allow for other graphic elements
 to be built using them.\par\filbreak

We'll look at the basic syntax for the primitives, and then discuss what
each parameter really means and how to specify what you want.
The parameters\index{primitives, parameters}\label{parameters} for each
of the graphic types are as follows:  literals are
in a {\btt typewriter} face, any required parameters for the primitive are
in \mbox{$\langle$ angle $\rangle$} brackets,
 and any {\it optional\/} parameters are within
\mbox{$\lbrack$ square $\rbrack$}
brackets. Please note that the relative ordering of the parameters
 {\it is\/} important, even
if you do not use any or all optional parameters. Also, it is does not
matter if you use upper- or lower-case letters for the primitives or markers.
\par\filbreak
\medskip
{\btt\char'134 special\char'173 tyl line}
 \Opt{measure}
\Opt{transform} \Prm{thick}\Coma\par
\hfil \Opt{vector}{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}} $ x_{\rm left}\,\Coma\>
y_{\rm bottom}\,\Coma\>
x_{\rm right}\, \Coma\> y_{\rm top}${\btt\char'175} \par

\noindent draws a line\index{{\bf line}} segment\index{line segments}
 from the point $\left( x_{\rm left}\, , \; y_{\rm
bottom}\right)$ to the point
$\left( x_{\rm right}\, ,\; y_{\rm top}\right)$ using a line of
thickness\index{line thickness}
\Prm{thick}.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl spline}
 \Opt{measure}\Opt{transform}\Prm{thick}\Coma\par
\hfil \Opt{vector}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Opt{s-type}\Opt{closure}\par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt X}$\>\langle dotsize\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Prm{numpts}\Coma $x_1\, \Coma\> y_1\, \Coma\> \ldots\>\Coma\>
 x_{\rm numpts}\, \Coma\> y_{\rm numpts}$ {\btt \char'175} \par

\noindent draws a smooth spline\index{{\bf spline}} curve through the integer points
 $x_1\, , \; y_1 ,\; \ldots$ \linebreak[4]
 $\; x_{\rm numpts}\, ,\; y_{\rm numpts}$
using a line of thickness \Prm{thick}. If the optional {\btt X} marker
\index{{\tt X}-marker} is specified, dots of diameter \Prm{dotsize} are
placed to mark the positon of the control points specified. This
may be useful for checking your data.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl ttspline} \Opt{measure}
\Opt{transform}\par
\hfil \Opt{vector}\Opt{s-type}\Opt{closure}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}} \par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt X}$\>\langle dotsize\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}
\Prm{numpts}\Coma
$x_1\, \Coma\> y_1\, \Coma\>\ldots\>\Coma\>
x_{\rm numpts}\,\Coma\> y_{\rm numpts}\,\Coma\>$\par
\hfil $thick_1\, \Coma\>\ldots\>
\Coma\> thick_{\rm numpts}$ {\btt \char'175} \par

\noindent draws a smooth spline through the integer points $x_1 , \; y_1 ,\;
\ldots$ using a\index{{\bf ttspline}}
line of varying thickness defined by $thick_i$ at each control point\index{ttspline, thicknesses}
$\left( x_i,\; y_i\right)$ (ergo {\underbar t}hick-{\underbar t}hin
splines). The {\btt X} marker is also available for marking the positions
of the specified control points. \par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl arc} \Opt{measure}
\Opt{transform} \Prm{thick}\Coma\par
\hfil \Opt{vector}
{\leavevmode\hbox{$\>\lbrack${\btt L}$\>\langle style\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}\Prm{radius}\Coma
{\leavevmode\hbox{$\>\lbrack${\btt @}$\>\langle cent_x\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle cent_y\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\rbrack$}}\par
\hfil\Prm{$angle_1$}\Coma \Prm{$angle_2$}{\btt \char'175} \par

\noindent draws an arc\index{{\bf arc}} of radius \Prm{arc-radius} going counter-clockwise
starting from \Prm{$angle_1$} degrees from zero, and \index{arcs, angles}
finishing at \Prm{$angle_2$} degrees around from zero. If the center point is not specified with
the {\btt @} marker\index{{\tt @}-marker}, the arc is assumed to be centered
at $(0,\, 0)$.\index{arcs, centering}
 Ellipses\index{ellipses} can be achieved by a simple scaling
 of a closed arc\index{oval, {\it see} ellipse}
since scaling and rotational transformations
 are about the {\it center\/} of the primitive.\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl label} \Opt{measure}
\Prm{face}\Coma $\;x\, \Coma\> y$\Coma {\btt "}\Prm{string}{\btt "}
{\btt\char'175}\par

\noindent places a simple label\index{{\bf label}} at $(x,\, y)$ using
 a font style\index{labels, font style}\index{labels, face} of
\Prm{face} (currently selectable by an integer: e.g.,
 |1| is amtt10. See page~\pageref{labelfonts} for a better list).
\Prm{String} is a simple sequence of letters and spaces contained
within matching double quotes ({\btt "}).\index{{\tt "}-marker}
Here, the case of the letters of \Prm{string} is taken  verbatim,
and it is {\it not}
interpreted;  {\TeX} macros or typesetting commands are not
usable here.\index{labels, strings} If you want to typeset fancier
labels, \TT is too late in the game.\par\filbreak

The optional parameter
\Prm{measure}\index{measurement}\index{units of measure} is any
of {\btt S}\index{{\tt S}-measure},
 {\btt P}\index{{\tt P}-measure},
or {\btt M}\index{{\tt M}-measure}
denoting that the integer
points, like $x_1,\; y_1,\;\ldots $ are measured in
scaled-points,\index{scaled points}
printer's-points\index{printer's points}, or millimeters\index{millimeters}
respectively. If none is specified, the measurement
of\index{measurement, default}
printer's-points is assumed. Just to refresh how big each of those units is:
\begin{itemize}
\item there are 72.27 printer's points {\it (pp)\/} per inch
\item and 65536 scaled-points {\it (sp)\/} per printer's point
\item and 25.4 millimeters {\it (mm)\/} per inch
\end{itemize}\par
  Also remember that the coordinates for the above
control points (like $x_{left}$ or $x_i$) are in {\it first quadrant}
cartesian coordinate-space\index{coordinate space system}. It is useful not to have to remember some
other coordinate systems, and makes things easier for
the user and user programs to interact with \TTN, which takes care
of such details.\par\filbreak

\Prm{Thick} is the pixel-thickness\index{line thickness}
\index{pixel thickness} of the vector font\index{vector font} to use. Currently
the range is from about 1 to 12 pixels thick (we'll talk more about these
sizes later). Here are some examples of lines having from 2 to 10 ``pixels''
 in even thicknesses.\index{line thickness, example}\par
\noindent\hskip 1in\begintyl{3truecm}[1in]
\special{tyl beg}
\special{tyl line m 2 2 4 11 26}
\special{tyl line m 4 12 23 15 10}
\special{tyl line m 6 15 20 25 13}
\special{tyl line m 8 26 9 31 23}
\special{tyl line m 10 33 2 33 16}
\special{tyl end}\endtyl
\par\filbreak
 \Prm{Vector} refers to the {\it
type\/} of vector\index{vector-types}\index{pens} to use,
 namely {\btt C}\index{{\tt C}-marker} for vectors that look as if they are
 drawn with a {\it circular\/} ``pen,''\index{circular pen}
 {\btt H}\index{{\tt H}-marker} for a {\it horizontal\/}
pen,\index{horizontal pen}
 and {\btt V}\index{{\tt V}-marker} for
{\it vertical\/} pen appearance\index{vertical pen}.
 A circular pen vector-type is the default\index{vector-types, default}. See also
section~\ref{vect-pens} for examples and a better description.\par\filbreak

\Prm{Style} \index{line style}\index{{\tt L}-marker}is the
 line-style to use when drawing. Currently, \TT is able to
provide solid (style |0|), dotted (style |1|), dashed (|2|), and dot-dashed (|3|)
line-styles.\index{line style, dotted}\index{line style, dashed}
\index{line style, solid}\index{line style, dot-dashed} The solid line-style is
the default. Here are some simple examples of the styles:\index{line styles, examples}\par
\begintyl{3truecm}[1in]
\special{tyl beg}
\special{tyl line m 2 L 0 (2 4 11 26)}
\special{tyl line m 2 L 1 (12 23 15 10)}
\special{tyl line m 2 L 2 (15 20 25 13)}
\special{tyl line m 2 L 3 (26 9 31 23)}
\special{tyl end}\endtyl
\par\filbreak

\Prm{S-type} is the kind of spline-basis\index{splines, types}\index{splines, basis}
to use when interpolating the spline
through the control points. Currently, {\btt B}\index{{\tt B}-marker}
 indicates the {\underbar b}-spline basis\index{B-spline basis}
(which interpolates a spline within the convex hull of the control points),
{\btt I}\index{{\tt I}-marker} indicates an
 {\underbar i}nterpolating B-spline\index{interpolating B-spline, basis} (goes through the points
specified), {\btt D}\index{{\tt D}-marker} for the Cardinal
basis,\index{Cardinal basis}
and {\btt K}\index{{\tt K}-marker} which
indicates the Catmull-Rom basis\index{Catmull-Rom basis} (which also
 interpolates a spline {\it through\/} the control points). The
Catmull basis is the default\index{splines, default basis} spline type in the current
implementation.\par\filbreak

\Prm{Closure}\index{closure}\index{splines, closure} is used to
indicate whether the spline is a closed \index{closed splines}
curve (the endpoints overlap), or an open curve\index{open spline} (the
default)\index{splines, default closure}. We use
the iconography of {\btt O}\index{{\tt O}-marker} for a closed curve,
 and {\btt U}\index{{\tt U}-marker} for an
open-ended curve.\par\filbreak

Now we come to describe what \Prm{transform} is all about. \TT
allows the user to modify the coordinates of the control points without
having to re-calculate their new positions by himself.
\index{design decisions}I tried to make the specification and modification
of {\it \TeX tyl's\/} primitives as painless and intuitive\index{user intuition} as possible. We
usually think more in terms of connecting dots and placing graphic elements,
 and not in terms of slopes, tangents and velocites which are messy at best,
and get more cumbersome from there.\par\filbreak

Geometric transforms\index{transformations, {\it see } transforms}
\index{geometric transforms} like scaling
(independently in the $X$ and $Y$ directions), rotating about the ``center''
of the graphic object (a primitive or a figure), and translating in the $X$ and $Y$ directions are
available for most of the primitives. The
format\index{{\bf transform}} for specifying some transformation on
the currently-specified points\index{transforms, parameters, format}
is:\par
\qquad{\btt T}\Coma\Prm{Sx}\Coma\Prm{Sy}\Coma\Prm{Tx}\Coma\Prm{Ty}\Coma\Prm{Rot}\Coma\par
\noindent where \Prm{Tx} and \Prm{Ty} are translations of the object in
 the $X$ and $Y$ direction by some signed distance according to the
current units of \Prm{measure}. \Prm{Rot} is a signed integer angle (in
degrees) by which
to rotate the primitive or figure counter-clockwise about its center.
  \Prm{Sx} and \Prm{Sy} are\index{transforms, parameters}
{\it integer\/} scale parameters representing the {\it floating-point\/} values of the
transform multiplied by 100 and truncated.
To obtain any transform, {\it all\/} the transform parameters must be
specified\index{transforms, parameters, requirement}.\par\filbreak

Two other special types of graphics capabilities are meant to be utilized
 by a
knowledgeable program, such as the music-typesetting\index{music} system being written at
the Ohio State University. These are:\par
\medskip
{\btt\char'134 special\char'173 tyl tieslur} \Opt{measure}
 \Prm{minthick}\Coma \Prm{maxthick}\Coma\par
\hfil \Prm{numpts}\Coma
$ x_1\, \Coma\> y_1\, \Coma\>\ldots\>\Coma\>
x_{\rm numpts}\,\Coma\> y_{\rm numpts}${\btt\char'175}\par

\noindent which draws a smooth spline curve through the
 points\index{{\bf tieslur}}\index{slurs}\index{ties}
$\left(x_i,\;y_i\right)$,
and uses a built-in algorithm to figure out the correct thicknesses of the
tie/slur between \Prm{minthick} and \Prm{maxthick}. These control points
 are  also in first quadrant cartesian coordinates, and a circular-pen
vector-type is used to draw the
spline.\index{tieslur, pen type}\index{tieslur, thicknesses}\index{tieslur,
vector type}\par\filbreak

\medskip
{\btt\char'134 special\char'173 tyl beam} \Opt{measure} \Prm{staffsize}\Coma
\Opt{beamtype}\par
\hfil $x_1\, \Coma\> y_1\, \Coma\> x_2\, \Coma\> y_2${\btt\char'175} \par

\noindent draws a music beam\index{{\bf beam}} from $\left(x_1,\;y_1\right)$ to
  $\left(x_2,\;y_2\right)$ (also in first quadrant space)
using a beam of \Prm{beamtype}\index{beam-types}
 {\btt G}\index{{\tt G}-marker} for a {\it grace\/}-note sized
beam,\index{beams, sizes}
 or {\btt R}\index{{\tt R}-marker}\index{beams, default size} (the default) for
{\it regular} sized beams in the specified
staff-size\index{beams, staff size}.
 For a description of staff sizes, see \cite{ross}.\par\filbreak

Finally, there are two more |\special|s that \TT can
understand. These are used to group any of the above graphic primitives together
into a ``symbol.''\index{symbol, {\it see} figure}  The commands are:\par
\medskip
{\btt\char'134 special\char'173 tyl beginfigure} \Opt{measure}
\Opt{transform}\par
\hfil{\leavevmode\hbox{$\>\lbrack${\btt W}$\>\langle width\/\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle height\rangle\,\rbrack\,$}}
{\leavevmode\hbox{$\>\lbrack${\btt F}$\>\langle width\/\rangle\,
\raise 2.5pt\hbox{\btt ,}\,\langle height\rangle\,\rbrack\,$}}
{\btt\char'175}\par
\noindent which opens a level of definition\index{{\bf beginfigure}},
and\par
\medskip
{\btt\char'134 special\char'173 tyl endfigure}{\btt\char'175}\par
\noindent which closes that level of definition\index{{\bf endfigure}}. These are analagous to
{\it push} and {\it pop} kinds of operations, with many levels of
recursive definition available. The optional {\btt F}
marker\index{{\tt F}-marker} specifies the final optimal
 width and height of the figure,\index{figures, fitting to size}
in terms of units of \Prm{measure}. This is useful for fitting a figure to a
specific size, so that you do not have to compute the scaling parameters
by yourself. This ability is often desireable if the figure was created by
some program that output the figure at a different scaling factor than you
require on the page. The {\btt W} marker\index{{\tt W}-marker} indicates the
width and height of the figure at the size that it was originally written,
which we assume the figure-making program output along with the definition
of the figure elements.\index{programs making figures}\index{graphic editors}
 For most
 practical purposes, you can let \TT\
compute the size of the figure as it was originally created, and then let it
fit the figure to the sizes requested by the {\btt F} marker.\par

Besides the implicit transform parameters created by using the {\btt F}
and/or {\btt W} markers, an explicit figure-level
tranformations\index{tranforms, figure-level}\index{figures, tranforms}
can be specified using the \Prm{transform} capability using units of
\Prm{measure} (or the default units of printer's
points).\index{measurement,default}
 Also, any transforms applied at a level of
definition are additive\index{transforms, additiveness}
over the lower-level definitions\index{figure definitions} and any
transformations that they may have
locally\index{figures, transforms}.\par\filbreak
%\vskip 10pt
%If this were the {\TeX book}, this paragraph would have three ``dangerous
%bend'' signs in front. \TT currently has a temporary
% ability to alter certain internal global
%variables from the |\special| level. This is meant mostly for debugging,
%hacking, and generally limited use. You are on your own with these, and
% I would discourage much use of it (since it may disappear soon).
% The basic call is\par
%{\btt\char'134 special\char'173 tyl param} \Prm{param-num} \Prm{value}{\btt\char'175}\par
%\noindent where \Prm{param-num} is currently one of\index{{\bf param}}
%\begin{itemize}
%\item {\tt 1}: for changing the current minimum number of intervals per
%spline span
%\item {\tt 2}: for changing the minimum number of intervals per arc
%spline-span
%\item {\tt 3}: for debugging the tie/slur clamping mechanism (skip it or not).
%\end{itemize}
% and \Prm{value} is the new value. For example,
%\begin{verbatim}
%  \special{tyl param 1  4}
%  \special{tyl param 3 = -1}
%\end{verbatim}
%the first sets the minimum number of intervals per spline span to $4$, and the
%second call says to {\it not\/} skip the clamping mechanism (the |=| sign
%is optional, of course). Once these
%variables are set, they are in effect for the rest of the document, or until
%changed with a matching |\special{tyl param...| invocation.
%See later chapters to understand these terms.\par

\Makeodd
E_O_F
else
  echo "will not over write ./doc/TYLMAN.04"
fi
chmod 644 ./doc/TYLMAN.04
if [ `wc -c ./doc/TYLMAN.04 | awk '{printf $1}'` -ne 18759 ]
then
echo `wc -c ./doc/TYLMAN.04 | awk '{print "Got " $1 ", Expected " 18759}'`
fi
echo "Finished archive 9 of 9"
exit